---
title: Version 0.22.0
description: Release notes and breaking changes.
---

---

<Warning>
This is currently a **beta release** and should be used with caution.

Use the following package versions:
```yaml
jaspr: 0.22.0-beta.0
jaspr_test: 0.22.0-beta.0
jaspr_builder: 0.22.0-beta.0
jaspr_cli: 0.22.0-beta.0
jaspr_serverpod: 0.6.0-beta.0
jaspr_router: 0.8.1-beta.0
jaspr_content: 0.4.5-beta.0
jaspr_flutter_embed: 0.4.10-beta.0
jaspr_riverpod: 0.4.2-beta.0
jaspr_web_compilers: 4.4.3-beta.0
```
</Warning>

## TLDR / Overview

Version 0.22.0 ships separate entrypoints for server and client environments to decrease magic in the framework and make it more transparent what is happening under the hood. It also splits all DOM related APIs into a separate library for better modularity and reimplements all HTML components as classes instead of functions.

**TL;DR**

- **Separate Entrypoints:** Each project can now contain a `main.server.dart` (in server and static mode) and `main.client.dart` (in all modes) file. Related APIs are updated to reflect this.
- **Improved @client initialization**: Any `@client` component is now initialized by using the new `ClientApp` component in `main.client.dart`, which can be wrapped with other components for sharing state, running custom initialization logic and more.
- **New `package:jaspr/dom.dart` library**: All DOM related APIs (HTML components, `Styles`, `css`, etc.) have been moved into a separate library for better modularity.
- **Reimplemented HTML Components as Classes**: All HTML components have been reimplemented as classes instead of functions, allowing `const` usage.
- **Allow binary responses**: The `AppContext.setStatusCode` method now accepts binary data for overriding the response body.
- **Various Styling Improvements**: New CSS properties like `animation` and `quotes`, improved properties like `Transition`, better support for dot-shorthands and more.

<Warning>
Most changes can be **automatically migrated** using the `jaspr migrate` command.

While using the beta, provide the target version manually using `jaspr migrate --target-version=0.22.0`.
If you are on latest Dart and want the migrations to use dot-shorthands, additionally add `--feature=dot-shorthands`.
</Warning>

---

## Project Entrypoints

The project can now contain separate entrypoints for server and client environments:

- `<file>.server.dart` (in server and static mode)
- `<file>.client.dart` (in all modes)

The generated global options file (previously `jaspr_options.dart`) is now generated as `<file>.server.options.dart` alongside the entrypoint, and an additional `<file>.client.options.dart` is generated for client-side code.

<Info>
All needed changes can be automatically applied using the `jaspr migrate` command.
</Info>

### Client Initialization

The default `main.client.dart` file should look like this:

```dart
// Previously 'browser.dart', now renamed.
import 'package:jaspr/client.dart';

// Generated options file.
import 'main.client.options.dart';

void main() {
  Jaspr.initializeApp(
    options: defaultClientOptions,
  );

  runApp(
    // New component to initialize @client components.
    const ClientApp(),
  );
}
```

This surfaces previously hidden functionality of the framework related to the initialization of `@client` components on the client and thereby makes it easier to debug and understand what is happening.

Futher, the new `ClientApp` component may be wrapped with other (Inherited) components to share state across multiple `@client` components, or to run custom initialization logic before calling `runApp`.

### Flutter Plugin Support

Jaspr supports using Flutter web plugins through the `jaspr_web_compilers` package. Part of the required setup logic related to plugins has now moved into the `.client.options.dart` file. To continue using plugins, make sure to use the latest version of `jaspr_web_compilers` together with the new entrypoint system.

### Changed `browser` library to `client`

The `package:jaspr/browser.dart` library has been renamed to `package:jaspr/client.dart` to better reflect its purpose. The migration can be performed automatically using the `jaspr migrate` command.

### Migration

<Info>
After upgrading Jaspr CLI to `0.22.0`, you can use the `jaspr migrate` command to **automatically migrate your code** to the new entrypoint system.
</Info>

In case you need or want to migrate your code manually, rename `lib/main.dart` to `lib/main.server.dart` and create a new `lib/main.client.dart` file with the content shown above. Additionally, rename all `package:jaspr/browser.dart` imports to `package:jaspr/client.dart`.

### Reason for the Change

The goal of this change is to reduce the "magic" in the framework and make it more transparent what is happening under the hood. This comes with the added benefit of enabling custom initialization logic, and sharing state across multiple `@client` components, a feature that was frequently requested.

This change also allowed to move parts of the `jaspr_web_compilers` package (fork of `build_web_compilers`) into the main Jaspr framework, which will make it easier to maintain the fork in the future and starts work towards removing the need for the fork altogether in the future.

## DOM APIs

All DOM related APIs (`div()` et al., `Styles`, `css`, `Color` et al., `events()`, `RawText`, and `ViewTransitionMixin`) have been moved into a separate `package:jaspr/dom.dart` library for better modularity.

### HTML Class Components

All HTML components have been reimplemented as classes instead of functions. This is technically a breaking change, but it is expected to not affect most users.

### Deprecated Helper Functions

Deprecated `text()`, `fragment()` and `raw()` functions in favor of `Component.text()`, `Component.fragment()` and `RawText`, respectively.

The new API is designed to work well with dot-shorthands while allowing `const` usage.

```dart
// Before:
text('Hello World');
fragment([ ... ]);
raw('<div>Raw HTML</div>');

// After (with dot-shorthands):
.text('Hello World');
.fragment([ ... ]);
RawText('<div>Raw HTML</div>');
```

### Migration

<Info>
After upgrading Jaspr CLI to `0.22.0`, you can use the `jaspr migrate` command to **automatically migrate (most of) your code** to the new entrypoint system.
</Info>

In case you need or want to migrate your code manually, add new `package:jaspr/dom.dart` imports where needed. 

In most cases, the new HTML class components should not need any migration, as they keep their lowercase names. One exception to this is when used with inferred typing (such as `var child = div([]);`), which may now require an explicit type annotation (such as `Component child = div([]);`) when assigning other values (such as `child = span([]);`).

### Reason for the Change

The new library reduces the "pollution" of the global namespace when importing `package:jaspr/jaspr.dart` and allows for more fine-grained control of imported APIs.

The class components allow for using `const` on html component trees, which can improve performance. Also this makes the overall code more consistent and aligned with best-practices for writing components. As an exception to the general rule, the HTML  components continue to use lowercase names to keep the familiar html-like syntax and differentiate them to other components.

## Binary Responses

The `context.setStatusCode` method now allows binary data (`Uint8List`) for overriding the response body. Respectively, the related `ResponseLike.body` property (returned from `renderComponent()`) is now a `Uint8List` instead of a `String`.

## New and Improved CSS Properties

The following css properties have been added to `Styles()` and `css.styles()`:

```dart
Animation animation
Quotes quotes
```

Also added:

- `Curve.linearFn()` easing function
- `Gap.row()` and `Gap.column()` constructors.
- `Flex.grow()`, `Flex.shrink()` and `Flex.basis()` constructors.
- `Border.all()` constructor.

The `duration` and `delay` properties of `Transition` now accept `Duration` instead of `double`. For convenience, `ms` and `seconds` extensions to `int` are added for simple conversion:

```dart
transition: Transition('width', duration: 2.seconds, delay: 300.ms),
```